/*
 * Copyright (c) 2011 Obix Labs Limited
 * Redistribution and use in source and binary forms, 
 * with or without modification, are permitted provided 
 * that the following conditions are met:
 * 
 * 		Redistribution of source code must retain the above 
 * 		copyright notice, this list of conditions and the 
 * 		following disclaimer.
 *
 * 		Redistribution in binary form must reproduce the 
 * 		above copyright notice, this list of conditions 
 * 		and the following disclaimer in the documentation 
 * 		and/or other materials provided with the distribution.
 * 
 * 	THIS SOFTWARE IS PROVIDED "AS IS," WITHOUT A WARRANTY OF 
 * 	ANY KIND. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS 
 * 	AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, 
 * 	FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, 
 * 	ARE HEREBY EXCLUDED. OBIX LABS LIMITED ("Obix Labs") AND ITS 
 * 	LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE 
 * 	AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR 
 * 	ITS DERIVATIVES. IN NO EVENT WILL Obix Labs OR ITS LICENSORS BE 
 * 	LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, 
 * 	INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE 
 * 	DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF 
 * 	LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE THIS 
 * 	SOFTWARE, EVEN IF Obix Labs HAS BEEN ADVISED OF THE POSSIBILITY OF 
 * 	SUCH DAMAGES.
 */
package com.obixlabs.commons.security;

import com.obixlabs.commons.util.CharacterSource;

/**
 * <p>
 * A {@link PasswordRequirement password rule} which ensures that a {@link PasswordBuffer password}
 * consists of a specified minimum number of characters. If applied to an empty buffer, this rule 
 * will append the specified minimum number of alpha characters to the buffer. So, for example, assume that the 
 * minimum required number of alpha characters is 8; if this rule is applied to an empty buffer, it will append 
 * 8 randomly chosen alpha characters to the buffer.  
 * </p>
 * <p>
 * This {@link PasswordRequirement rule} can serve as the base password rule in an application as it 
 * provides an easy way to generate a candidate password {@link String string}. Subsequent rules can then
 * be applied to that string in order to <i><b>harden</b></i> it.
 * </p>
 */
public class SimpleAlphaCharsFillPasswordRequirement extends AbstractPasswordRequirement
{
	/**
	 * <p>
	 * The minimum number of characters required for the password string.
	 * </p>
	 */
	private int minimumRequiredLength;	

        /**
         * <p>
         * Overrides {@link AbstractPasswordRequirement#AbstractPasswordRequirement(CharacterSource)
         * superclass constructor} which accepts a {@link CharacterSource} as an argument; but additionally also accepts the 
         * minimum desired password length.
         * </p>
         * 
         * @param characterSource       See {@link AbstractPasswordRequirement#AbstractPasswordRequirement(CharacterSource) parent class constructor} 
         * for details.
         * @param minimumRequiredLength The minimum required length for the password.
         */	
	public SimpleAlphaCharsFillPasswordRequirement(CharacterSource characterSource,
	                                                                                                        int minimumRequiredLength)
	{ 
		super(characterSource);
		this.minimumRequiredLength = minimumRequiredLength;
	}
	
        /**
         * <p>
         * Overrides default {@link AbstractPasswordRequirement#AbstractPasswordRequirement()
         * superclass constructor}, but accepts the minimum desired password length as an argument.
         * </p>
         * 
         * @param minimumRequiredLength The minimum required length for the password.
         */	
	public SimpleAlphaCharsFillPasswordRequirement(int minimumRequiredLength)
	{ 
		super();
		this.minimumRequiredLength = minimumRequiredLength;
	}	
	

        /**
         * <p>
         * Overrides {@link AbstractPasswordRequirement#AbstractPasswordRequirement(CharacterSource, int)
         * superclass constructor} which accepts a {@link CharacterSource} and a prime number as arguments; 
         * but additionally also accepts the minimum desired password length.
         * </p>
         * 
         * @param characterSource       See {@link AbstractPasswordRequirement#AbstractPasswordRequirement(CharacterSource, int)  parent class constructor} 
         * for details.
         * @param prime See {@link AbstractPasswordRequirement#AbstractPasswordRequirement(CharacterSource, int)  parent class constructor} 
         * for details.
         * @param minimumRequiredLength The minimum required length for the password.
         */   	
	public SimpleAlphaCharsFillPasswordRequirement(   CharacterSource characterSource, 
	                                                                                                        int prime, int minimumRequiredLength)
	{
		super(characterSource, prime);
		this.minimumRequiredLength = minimumRequiredLength;
	}

	@Override
	public boolean apply(PasswordBuffer buffer)
	{
		boolean result ;
			
		while (buffer.length()<minimumRequiredLength)
		{
			if (!buffer.append(getCharacterSource().nextAlphaChar()))
				break;
		}
		
		if (buffer.length()>= minimumRequiredLength)
			result = true;
		else result = false;
		
		return result;
	}
	
	@Override
	public String getDescription() {return "Minimum length of " + minimumRequiredLength + " characters."; }
}